'\" t
.\"___INFO__MARK_BEGIN__
.\"
.\" Copyright: 2004 by Sun Microsystems, Inc.
.\"
.\" Portions of this code are Copyright 2011 Univa Inc.
.\"
.\"___INFO__MARK_END__
.\"
.\" $RCSfile: submit.1,v $     Last Update: $Date: 2010/01/12 14:41:02 $     Revision: $Revision: 1.103 $
.\"
.\"
.\" Some handy macro definitions [from Tom Christensen's man(1) manual page].
.\"
.de SB		\" small and bold
.if !"\\$1"" \\s-2\\fB\&\\$1\\s0\\fR\\$2 \\$3 \\$4 \\$5
..
.\"
.de T		\" switch to typewriter font
.ft CW		\" probably want CW if you don't have TA font
..
.\"
.de TY		\" put $1 in typewriter font
.if t .T
.if n ``\c
\\$1\c
.if t .ft P
.if n \&''\c
\\$2
..
.\"
.de M		\" man page reference
\\fI\\$1\\fR\\|(\\$2)\\$3
..
.TH SUBMIT 1 "$Date: 2010/01/12 14:41:02 $" "xxRELxx" "xxQS_NAMExx User Commands"
.SH NAME
.IP "qsub   \-" 1i
submit a batch job to xxQS_NAMExx.
.IP "qsh    \-" 1i
submit an interactive X-windows session to xxQS_NAMExx.
.IP "qlogin \-" 1i
submit an interactive login session to xxQS_NAMExx.
.IP "qrsh   \-" 1i
submit an interactive rsh session to xxQS_NAMExx.
.IP "qalter \-" 1i
modify a pending or running batch job of xxQS_NAMExx.
.IP "qresub \-" 1i
submit a copy of an existing xxQS_NAMExx job.
.\"
.\"
.SH SYNTAX
.B qsub
[
.B options
] [
.B command 
[
.B command_args
] | --
[
.B command_args
]]
.PP
.B qsh
[
.B options
] [
.B -- xterm_args
]
.PP
.B qlogin
[
.B options
]
.PP
.B qrsh
[
.B options
] [
.B command
[
.B command_args
]]
.PP
.B qalter
[
.B options
]
.B wc_job_range_list 
[
.B --
[
.B command_args
]]
.PP
.B qalter
[
.B options
]
.B -u user_list | -uall
[
.B --
[
.B command_args
]]   
.PP
.B qresub
[
.B options
]
.B job_id_list
.\"
.\"
.SH DESCRIPTION

.I Qsub
submits batch jobs to the xxQS_NAMExx queuing system. xxQS_NAMExx supports
single- and multiple-node jobs. \fBCommand\fP can be a path to a
binary or a script (see \fB-b\fP below) which contains the commands to be
run by the job using a shell (for example,
.M sh 1
or
.M csh 1 ).
Arguments to the command are given as \fBcommand_args\fP to
.I qsub .
If \fBcommand\fP is handled as a script then it is possible to embed flags
in the script.  If the first two characters of a script line either
match '#$' or are equal to the prefix string defined with the \fB-C\fP option
described below, the line is parsed for embedded command flags.
.PP
.I Qsh
submits an interactive X-windows session to xxQS_NAMExx. An
.M xterm 1
is brought up from the executing machine with the display directed either to
the X-server indicated by the DISPLAY environment variable or as specified
with the \fI\-display qsh\fP option. Interactive jobs are not spooled if no
resource is
available to execute them. They are either dispatched to a suitable machine
for execution immediately or the user submitting the job is notified by
.I qsh
that appropriate resources to execute the job are not available.
\fBxterm_args\fP are passed to the
.M xterm 1
executable.  Note, however, that the \fI\-e\fP and \fI\-ls\fP xterm options
do not work with
.I qsh .
.PP
.I Qlogin
is similar to
.I qsh
in that it submits an interactive job
to the queuing system. It does not open an
.M xterm 1
window on the
X display, but uses the current terminal for user I/O. Usually,
.I qlogin
establishes a
.M telnet 1
connection with the remote host, using
standard client- and server-side commands. These commands can
be configured with the \fBqlogin_daemon\fP (server-side,
xxQS_NAMExx
.I telnetd
if not set, otherwise something
like /usr/sbin/in.telnetd) and \fBqlogin_command\fP (client-side,
xxQS_NAMExx
.I telnet
if not set, otherwise
something like /usr/bin/telnet) parameters in the global and
local configuration settings of
.M xxqs_name_sxx_conf 5 .
The client side command is automatically
parameterized with the remote host name and port number to which to
connect, resulting in an invocation like
.IP
/usr/bin/telnet my_exec_host 2442
.PP
for example.
.I Qlogin
is invoked exactly like
.I qsh
and its jobs can only run on INTERACTIVE queues.
.I Qlogin
jobs can only be used if the
.M xxqs_name_sxx_execd 8
is running under the root account.
.PP
.I Qrsh
is similar to 
.I qlogin
in that it submits an interactive job to the queuing system. 
It uses the current terminal for user I/O. 
Usually,
.I qrsh 
establishes a 
.M rsh 1
connection with the remote host. If no command is given to \fIqrsh\fP, an 
.M rlogin 1
session is established.
The server-side commands used can be configured 
with the \fBrsh_daemon\fP and \fBrlogin_daemon\fP
parameters in the global and local configuration settings of 
.M xxqs_name_sxx_conf 5 .
An xxQS_NAMExx
.I rshd
or
.I rlogind
is used if the parameters are not set. If the parameters are set, they should be
set to something like /usr/sbin/in.rshd or /usr/sbin/in.rlogind.
On the client-side, the \fBrsh_command\fP and \fBrlogin_command\fP parameters
can be set in the global and local configuration settings of 
.M xxqs_name_sxx_conf 5 . 
If they are not set, special xxQS_NAMExx
.M rsh 1
and
.M rlogin 1
binaries delivered with xxQS_NAMExx are used.
Use the cluster configuration parameters to integrate mechanisms like
.I ssh
or the
.M rsh 1
and
.M rlogin 1
facilities supplied with the operating system.
.PP
.I Qrsh
jobs can only run in INTERACTIVE queues unless the option \fB-now no\fP is
used (see below).
They can also only be run, if the 
.M xxqs_name_sxx_execd 8
is running under the root account.
.PP
.I Qrsh
provides an additional useful feature for integrating with
interactive tools providing a specific command shell. If the environment
variable
.B QRSH_WRAPPER
is set when
.I qrsh
is invoked, the command interpreter pointed to by
.B QRSH_WRAPPER
will be executed to run
.I qrsh
commands instead of the users login shell or any shell specified in the
.I qrsh
command-line.
The options \fB-cwd\fP,  \fB-v\fP,  \fB-V\fP,  and \fB-display\fP only 
apply to batch jobs.
.PP
.I Qalter
can be used to change the attributes of pending jobs. For array jobs
with a mix of running and pending tasks
(see the \fB\-t\fP option below), modification with
.I qalter
only affects the pending tasks.
.I Qalter
can change most of the 
characteristics of a job (see the corresponding statements in the OPTIONS 
section below), including those which were defined as embedded flags in the 
script file (see above).  Some submit options, such as the job script, cannot
be changed with
I. qalter.
.PP
.I Qresub
allows the user to create jobs as copies of existing pending or running
jobs. The copied jobs will have exactly the same attributes as the ones
from which they were copied, except with a new job ID and with a cleared
hold state. The only modification to
the copied jobs supported by
.I qresub
is assignment of a new hold state with the
\fB\-h\fP option. This option can be used to first copy a job and then change
its attributes via \fIqalter\fP.
.PP
Only a manager can use
.I qresub
on jobs submitted by another user.  Regular users can only use
.I qresub
on their own jobs.
.PP
For \fIqsub\fP, \fIqsh\fP, \fIqrsh\fP, and \fIqlogin\fP
the administrator and the user may define
default request files (see
.M xxqs_name_sxx_request 5 )
which can contain any of the
options described below.
If an option in a default request file is understood by
.I qsub
and
.I qlogin
but not by
.I qsh
the option is silently ignored if
.I qsh
is invoked. Thus you can 
maintain shared default request files for both
.I qsub
and \fIqsh\fP.
.PP
A cluster wide default request file
may be placed under $xxQS_NAME_Sxx_ROOT/$xxQS_NAME_Sxx_CELL/common/xxqs_name_sxx_request.
User private default request files are processed under the
locations $HOME/.xxqs_name_sxx_request and $cwd/.xxqs_name_sxx_request. The working
directory local default request file has the highest precedence,
then the home directory located file and then the cluster global
file.
The option arguments, the embedded script flags and the options
in the default request files are
processed in the following order:
.PP
.RS
.nf
left to right in the script line,
left to right in the default request files,
from top to bottom of the script file (\fIqsub\fP only),
from top to bottom of default request files,
from left to right of the command line.
.fi
.RE
.PP
In other words, the command line can be used to override
the embedded flags and the default request settings.
The embedded flags, however, will override the default
settings.
.PP
\fBNote\fP, that the
.I -clear
option can be used to discard any previous settings at any
time in a default request file, in the embedded script flags, or
in a
command-line option. It is, however, not available with \fIqalter\fP.
.PP
The
options described below can be requested either hard or soft.
By default, all requests are considered hard until the \fB\-soft\fP option (see
below) is encountered. The hard/soft status remains in effect
until its counterpart is encountered again.
If all the hard requests for a job cannot 
be met, the job will not be scheduled.
Jobs which cannot be run at the present time
remain spooled.
.\"
.\"
.SH OPTIONS
.IP "\fB\-@ optionfile\fP"
Forces
\fIqsub\fP, \fIqrsh\fP, \fIqsh\fP, or \fIqlogin\fP
to use the
options contained in \fBoptionfile\fP. The indicated 
file may contain all valid
options. Comment lines must start with a "#" sign.
.\"
.IP "\fB\-a date_time\fP"
Available for \fIqsub\fP and \fIqalter\fP only.
.sp 1
Defines or redefines
the time and date at which a job is eligible for execution. \fBDate_time\fP
conforms to [[CC]]YY]MMDDhhmm[.SS], for the details, please see \fBDate_time\fP in:
.M sge_types 1 .
.sp 1
If this option is used with \fIqsub\fP or if a corresponding value is 
specified in \fIqmon\fP then a parameter named \fBa\fP and the value
in the format CCYYMMDDhhmm.SS will be passed to the defined JSV instances
(see \fB\-jsv\fP option below or find more information concerning JSV in
.M jsv 1 )
.
.\"
.IP "\fB\-ac variable[=value],...\fP"
Available for \fIqsub\fP, \fIqsh\fP, \fIqrsh\fP, \fIqlogin\fP and
\fIqalter\fP only.
.sp 1
Adds the given name/value pair(s) to the job's context. \fBValue\fP may be
omitted. xxQS_NAMExx appends the given argument to the list of context
variables for the job.
Multiple \fB\-ac\fP, \fB\-dc\fP, and \fB\-sc\fP options may be given.
The order is important here.
.sp 1
The outcome of the evaluation of all \fB\-ac\fP, \fB\-dc\fP, and \fB\-sc\fP 
options or corresponding values in \fIqmon\fP is passed to defined JSV 
instances as parameter with the name \fB\aac\fP.
(see \fB\-jsv\fP option below or find more information concerning JSV in
.M jsv 1 )
.
.SP 1
.I QALTER
allows changing this option even while the job executes.
.\"
.IP "\fB\-ar ar_id\fP"
Available for \fIqsub\fP, \fIqalter\fP, \fIqrsh\fP, \fIqsh\fP, or \fIqlogin\fP
only.
.sp 1
Assigns the submitted job to be a part of an existing Advance Reservation. 
The complete list of existing Advance Reservations can be obtained using the
.M qrstat 1
command.
.sp 1
Note that the
\fB\-ar\fP
option adds implicitly the \fB\-w e\fP option if not otherwise requested.
.sp 1
.I Qalter
allows changing this option even while the job executes. The modified
parameter will only be in effect after a restart or migration of the
job however.
.sp 1
If this option or a corresponding value in \fIqmon\fP is specified then
this value will be passed to defined JSV
instances as parameter with the name \fB\aar\fP. 
(see \fB\-jsv\fP option below or find more information concerning JSV in
.M jsv 1 )
.
.\"
.IP "\fB\-A account_string\fP"
Available for \fIqsub\fP, \fIqsh\fP, \fIqrsh\fP, \fIqlogin\fP and
\fIqalter\fP only.
.sp 1
Identifies the account to which the resource consumption of the job
should be charged. The \fBaccount_string\fP should conform to the \fBname\fP
definition in
M sge_types 1 .
In the absence of this parameter xxQS_NAMExx 
will place the default account string "xxqs_name_sxx" in the accounting record
of the job.
.sp 1
.I Qalter
allows changing this option even while the job executes.
.sp 1
If this option or a corresponding value in \fIqmon\fP is specified then
this value will be passed to defined JSV
instances as parameter with the name \fBA\fP.
(see \fB\-jsv\fP option below or find more information concerning JSV in
.M jsv 1 )
.
.\"
.IP "\fB\-binding [ binding_instance ] binding_strategy\fP"
A job can request a specific processor core binding (processor affinity)
with this parameter. This request is neither a hard nor a soft request,
it is a hint for the execution host to do this if possible.
Please note that the requested binding strategy is not used for
resource  selection  within  xxQS_NAMExx.  As a result an execution host
might be selected where xxQS_NAMExx does not even know the hardware topology
and therefore is not able to apply the requested binding.
.sp
To enforce xxQS_NAMExx to select hardware on which the binding can be applied
please use the \fB-l\fP switch in combination with the complex
attribute \fBm_topology\fP.
.sp
\fBbinding_instance\fP is an optional parameter. It might either be
\fBenv\fP, \fBpe\fP or \fBset\fP depending on which instance should accomplish the
job to core binding. If the value for \fBbinding_instance\fP is
not specified then \fBset\fP will be used.
.sp
\fBenv\fP means that the environment variable \fBSGE_BINDING\fP will be
exported to the job environment of the job. This variable contains the
selected operating system internal processor numbers.
They might be more than selected cores in presence of SMT or CMT
because each core could be represented by multiple processor identifiers.
The processor numbers are space separated.
.sp
\fBpe\fP means that the information about the selected cores appears in
the fourth column of the \fBpe_hostfile\fP. Here the logical core and socket
numbers are printed (they start at 0 and have no holes) in colon separated
pairs (i.e. 0,0:1,0 which means core 0 on socket 0 and core 0 on socket 1).
For more information about the $pe_hostfile check
.M xxqs_name_sxx_pe 5  
.sp
\fBset\fP (default if nothing else is specified). The binding strategy is
applied by xxQS_NAMExx. How this is achieved depends on the underlying
hardware architecture of the execution host where the submitted job
will be started.
.sp
On Solaris 10 hosts a processor set will be created
where the job can exclusively run in.
Because of operating system limitations at least one core
must remain unbound. This resource could of course
used by an unbound job.
.sp
On Linux hosts a processor affinity mask will be set to
restrict  the job to run exclusively on the selected cores.
The operating system allows other unbound processes
to use these cores.
Please note that on Linux the binding requires a Linux kernel
version of 2.6.16 or greater. It might be even possible to use
a kernel with lower version number but in that case additional
kernel patches have to be applied. The \fBloadcheck\fP tool in the
utilbin directory can be used to check if the hosts capabilities.
You can also use the \fB-sep\fP in combination with \fB-cb\fP of
.M qconf 5
command to identify if xxQS_NAMExx is able to recognize the
hardware topology.
.sp
Possible values for \fBbinding_strategy\fP are as follows:
.sp
.nf
.ta \w''u
    linear:<amount>[:<socket>,<core>]
    striding:<amount>:<n>[:<socket>,<core>]
    explicit:[<socket>,<core>;...]<socket>,<core>
.fi
.sp
For the binding strategy linear and striding there is an optional
socket and core pair attached. These denotes the mandatory
starting point for the first core to bind on.
.sp
\fBlinear\fP means that xxQS_NAMExx tries to bind the job on \fBamount\fP
successive cores. If \fBsocket\fP and \fBcore\fP is omitted then xxQS_NAMExx
first allocates successive cores on the first empty socket found.
Empty means that there are no jobs bound to the socket by xxQS_NAMExx.
If this is not  possible or is not sufficient xxQS_NAMExx tries to find
(further) cores on the socket with the most unbound cores and so on.
If the amount of allocated cores is lower than requested cores, no
binding is done for the job. If \fBsocket\fP and \fBcore\fP is specified
then xxQS_NAMExx tries to find amount of empty cores beginning with this
starting point. If this is not possible then binding is not done.
.sp
\fBstriding\fP means that xxQS_NAMExx tries to find cores with a certain offset.
It will select \fBamount\fP of empty cores with a offset of \fBn\fP -1 cores
in between. Start point for the search algorithm is socket 0 core 0. As soon as
\fBamount\fP cores are found they will be used to do the job binding.
If there are not enough empty cores or if correct offset cannot
be achieved then there will be no binding done.
.sp
\fBexplicit\fP binds the specified sockets and cores that are mentioned in the
provided socket/core list. Each socket/core pair has to be specified only once. If a
socket/core pair is already in use by a different job the whole binding request
will be ignored.
.sp
\fBQalter\fP allows changing this option even while the job executes. The
modified parameter will only be in effect after a restart or migration
of the job, however.
.sp
If this option or a corresponding value in qmon is specified then these 
values will be passed to defined JSV instances as parameters with the names 
\fBbinding_strategy\fP, \fBbinding_type\fP, \fBbinding_amount\fP,
\fBbinding_step\fP, \fBbinding_socket\fP, \fBbinding_core\fP,
\fBbinding_exp_n\fP, \fBbinding_exp_socket<id>\fP, \fBbinding_exp_core<id>\fP.
.sp
Please note that the length of the socket/core value list of the explicit 
binding is reported as \fBbinding_exp_n\fP. \fB<id>\fP will be replaced 
by the position of the socket/core pair within the explicit list (0 <= \fBid\fP < \fBbinding_exp_n\fP). 
The first socket/core pair of the explicit binding will be reported 
with the parameter names \fBbinding_exp_socket0\fP
and binding_exp_core0.
.sp
Values that do not apply for the specified binding will not be reported to JSV.
E.g. \fBbinding_step\fP will only be reported for the striding binding and all
\fBbinding_exp_*\fP values will passed to JSV if explicit binding was specified.  
(see -jsv  option  below or find more information concerning JSV in jsv(1))
.\"
.IP "\fB\-b y[es]|n[o]\fP"
Available for \fIqsub\fP, \fIqrsh\fP only. \fIQalter\fP does not allow
changing this option. This option cannot be embedded in the script file itself.
.sp 1
Gives the user the possibility to indicate explicitly whether
\fBcommand\fP should be treated as binary or script. If the value
of \fB\-b\fP is 'y', then \fBcommand\fP  may be a binary or script.
The \fBcommand\fP might not be accessible from the submission host.
Nothing except the path of the \fBcommand\fP will be transferred
from the submission host to the execution host. Path aliasing will
be applied to the path of \fBcommand\fP before \fBcommand\fP will
be executed.
.sp 1
If the value of \fB\-b\fP is 'n' then \fBcommand\fP needs to be a
script and it will be handled as script. The script file has to be
accessible by the submission host. It will be transferred to the
execution host. \fIqsub\fP/\fIqrsh\fP will search directive prefixes
within script.
.sp 1
\fIqsub\fP will implicitly use \fB-b n\fP whereas \fIqrsh\fP will apply
the \fB-b y\fP option if nothing else is specified.
.sp 1
The value specified with this option or the corresponding value specified in
\fIqmon\fP will only be passed to defined JSV instances if the value is \fIyes\fP.
The name of the parameter will be \fBb\fP. The value will be \fBy\fP also
when then long form \fByes\fP was specified during submission.
(see \fB\-jsv\fP option below or find more information concerning JSV in
.M jsv 1 )
.
.sp
Please note that submission of \fBcommand\fP as script (\fB\-b n\fP) can have a significant 
performance impact, especially for short running jobs and big job scripts.
Script submission adds a number of operations to the submission process:
The job script needs to be
.nf
- parsed at client side (for special comments)
- transferred from submit client to qmaster
- spooled in qmaster
- transferred to execd at job execution
- spooled in execd
- removed from spooling both in execd and qmaster once the job is done
.fi
If job scripts are available on the execution nodes, e.g. via NFS, binary 
submission can be the better choice.
.\"
.IP "\fB\-c occasion_specifier\fP"
Available for \fIqsub\fP and \fIqalter\fP only.
.sp 1
Defines or redefines whether the job should be checkpointed, and if so,
under what circumstances. The specification of the checkpointing occasions
with this option overwrites the definitions of the \fIwhen\fP parameter in
the checkpointing environment (see
.M checkpoint 5 )
referenced by the \fIqsub \-ckpt\fP switch.
Possible values for \fBoccasion_specifier\fP are
.sp 1
.nf
.ta \w'<interval>  'u
n	no checkpoint is performed.
s	checkpoint when batch server is shut down.
m	checkpoint at minimum CPU interval.
x	checkpoint when job gets suspended.
<interval>	checkpoint in the specified time interval.
.fi
.sp 1
The minimum CPU interval is defined in the queue configuration (see
.M queue_conf 5
for details).
<interval> has to be specified in the format hh:mm:ss.
The maximum of <interval> and the queue's minimum CPU
interval is used if <interval> is specified. This is done to ensure
that a machine is not overloaded by checkpoints being generated too
frequently.
.sp 1
The value specified with this option or the corresponding value specified in
\fIqmon\fP will be passed to defined JSV instances.
The <interval> will be available as parameter with the name \fBc_interval\fP.
The character sequence specified will be available as parameter with the name
\fBc_occasion\fP. Please note that if you change \fBc_occasion\fP via JSV then
the last setting of \fBc_interval\fP will be overwritten and vice versa.
(see \fB\-jsv\fP option below or find more information concerning JSV in
.M jsv 1 )

.\"
.IP "\fB\-ckpt ckpt_name\fP"
Available for \fIqsub\fP and \fIqalter\fP only.
.sp 1
Selects the checkpointing environment (see
.M checkpoint 5 )
to be used for 
checkpointing the job. Also declares the job to be a checkpointing job. 
.sp 1
If this option or a corresponding value in \fIqmon\fP is specified then
this value will be passed to defined JSV
instances as parameter with the name \fBckpt\fP.
(see \fB\-jsv\fP option below or find more information concerning JSV in
.M jsv 1 )
.
.\"
.IP "\fB\-clear\fP"
Available for \fIqsub\fP, \fIqsh\fP, \fIqrsh\fP, and \fIqlogin\fP
only.
.sp 1
Causes all elements of the job to be reset to the initial default status
prior to applying any modifications (if any) appearing in this specific
command.
.\"
.IP "\fB\-cwd\fP"
Available for \fIqsub\fP, \fIqsh\fP, \fIqrsh\fP and
\fIqalter\fP only.
.sp 1
Execute the job from the current working directory.
This switch will activate xxQS_NAMExx's path aliasing facility, if the
corresponding
configuration files are present (see
.M xxqs_name_sxx_aliases 5 ).
.sp 1
In the case of \fIqalter\fP, the previous definition of the current working
directory will be overwritten if \fIqalter\fP is executed from a
different directory than the preceding \fIqsub\fP or \fIqalter\fP.
.sp 1
.I Qalter
allows changing this option even while the job executes. The modified
parameter will only be in effect after a restart or migration of the job,
however.
.sp 1
If this option or a corresponding value in \fIqmon\fP is specified then
this value will be passed to defined JSV
instances as parameter with the name \fBcwd\fP. The value of this parameter
will be the absolute path to the current working directory. JSV scripts can
remove the path from jobs during the verification process by setting the 
value of this parameter to an empty string. As a result the job
behaves as if \fB-cwd\fP was not specified during job submission.
(see \fB\-jsv\fP option below or find more information concerning JSV in
.M jsv 1 )
.

.\"
.IP "\fB\-C prefix_string\fP"
Available for \fIqsub\fP and \fIqrsh\fP with script submission (\fB-b n\fP).
.sp 1
.I Prefix_string
defines the prefix that declares a directive in the
job's command. The prefix is not a job attribute, but
affects the behavior of \fIqsub\fP and \fIqrsh\fP. If \fBprefix\fP is a
null string, the command will not be scanned for embedded directives.
.br
The directive prefix consists of two ASCII characters which,
when appearing in the first two bytes of a script line,
indicate that what follows is an xxQS_NAMExx command.
The default is "#$".
.br
The user should be aware that changing the first delimiting character can
produce unforeseen side effects. If the script file contains anything
other than a "#" character in the first byte position of the line, the shell
processor for the job will reject the line and may exit the job
prematurely.
.br
If the -C option is present in the script file, it is ignored.
.\"
.IP "\fB\-dc variable,...\fP"
Available for \fIqsub\fP, \fIqsh\fP, \fIqrsh\fP, \fIqlogin\fP and
\fIqalter\fP only.
.sp 1
Removes the given variable(s) from the job's context. 
Multiple \fB\-ac\fP, \fB\-dc\fP, and \fB\-sc\fP options may be given.
The order is important.
.sp 1
.I Qalter
allows changing this option even while the job executes.
.sp 1
The outcome of the evaluation of all \fB\-ac\fP, \fB\-dc\fP, and \fB\-sc\fP
options or corresponding values in \fIqmon\fP is passed to defined JSV
instances as parameter with the name \fB\aac\fP.
(see \fB\-jsv\fP option below or find more information concerning JSV in
.M jsv 1 )
.
.\"
.IP "\fB\-display display_specifier\fP"
Available for \fIqsh\fP and \fIqrsh with command\fP.
.sp 1
Directs
.M xterm 1
to use
.B display_specifier
in order to contact the X server.
The \fBdisplay_specifier\fP has to contain the hostname part of the display name (e.g. myhost:1). 
Local display names (e.g. :0) cannot be used in grid environments.
Values set with the \fB\-display\fP option overwrite settings from the submission environment 
and from \fB\-v\fP command line options.
.sp 1
If this option or a corresponding value in \fIqmon\fP is specified then
this value will be passed to defined JSV
instances as parameter with the name \fBdisplay\fP. This value will also
be available in the job environment which might optionally be passed to JSV
scripts. The variable name will be \fBDISPLAY\fP.
(see \fB\-jsv\fP option below or find more information concerning JSV in
.M jsv 1 )
.
.\"
.IP "\fB\-dl date_time\fP"
Available for \fIqsub\fP, \fIqsh\fP, \fIqrsh\fP, \fIqlogin\fP and
\fIqalter\fP only.
.sp 1
Specifies the deadline initiation time in [[CC]YY]MMDDhhmm[.SS] format (see
\fB\-a\fP option above). The deadline initiation time is the time at
which a deadline job has to reach top priority to be able to complete
within a given deadline. Before the deadline initiation time the
priority of a deadline job will be raised steadily until it reaches the
maximum as configured by the xxQS_NAMExx administrator.
.sp 1
This option is applicable only for users allowed to submit deadline jobs.
.sp 1
If this option or a corresponding value in \fIqmon\fP is specified then
this value will be passed to defined JSV
instances as parameter with the name \fBdl\fP. The format for the date_time value
is CCYYMMDDhhmm.SS (see \fB\-jsv\fP option below or find more information concerning JSV in
.M jsv 1 )
.

.\"
.IP "\fB\-e [[hostname]:]path,...\fP"
Available for \fIqsub\fP, \fIqsh\fP, \fIqrsh\fP, \fIqlogin\fP and
\fIqalter\fP only.
.sp 1
Defines or redefines
the path used for the standard error stream of the job. For
\fIqsh\fP, \fIqrsh\fP and \fIqlogin\fP only the standard error
stream of prolog and epilog is redirected.
If the \fBpath\fP constitutes an absolute path name, the
error-path attribute of the job is set to \fBpath\fP, including
the \fBhostname\fP. If the path name is relative, xxQS_NAMExx
expands \fBpath\fP either with the current working directory
path (if the \fB\-cwd\fP switch (see above) is also
specified) or with the home directory path. If 
\fBhostname\fP is present, the standard error stream will be
placed in the corresponding location only if the job runs on
the specified host. If the path contains a ":" without a
\fBhostname\fP, a leading ":" has to be specified.
.sp 1
By default the file name for interactive jobs is \fI/dev/null\fP. For
batch jobs the default file name has the form \fIjob_name.\fPe\fIjob_id\fP and
\fIjob_name.\fPe\fIjob_id\fP.\fBtask_id\fP for array job tasks (see
\fB\-t\fP option below).
.sp 1
If \fBpath\fP is a directory, the standard error stream of the
job will be put in this directory under the default file name.
If the pathname contains certain pseudo environment variables,
their value will be expanded at runtime of the job and will be used
to constitute the standard error stream path name. The following
pseudo environment variables are supported currently:
.sp 1
.nf
.ta \w'$JOB_NAME   'u
$HOME	home directory on execution machine
$USER	user ID of job owner
$JOB_ID	current job ID
$JOB_NAME	current job name (see \fB\-N\fP option)
$HOSTNAME	name of the execution host
$TASK_ID	array job task index number
.fi
.sp 1
Alternatively to $HOME the tilde sign "~" can be used as common in
.M csh 1
or
.M ksh 1 .
Note, that the "~" sign also works in combination with user names,
so that "~<user>" expands to the home directory of <user>. Using
another user ID than that of the job owner
requires corresponding permissions, of course.
.sp 1
.I Qalter
allows changing this option even while the job executes. The modified
parameter will only be in effect after a restart or migration of the job,
however.
.sp 1
If this option or a corresponding value in \fIqmon\fP is specified then
this value will be passed to defined JSV
instances as parameter with the name \fBe\fP.
(see \fB\-jsv\fP option below or find more information concerning JSV in
.M jsv 1 )
.
.\"
.IP "\fB\-hard\fP"
Available for \fIqsub\fP, \fIqsh\fP, \fIqrsh\fP, \fIqlogin\fP and
\fIqalter\fP only.
.sp 1
Signifies that all \fB\-q\fP and \fB\-l\fP resource requirements following in the
command line will be hard requirements and must be satisfied
in full before a job can be scheduled.
.br
As xxQS_NAMExx scans the command line and script file for xxQS_NAMExx
options and parameters it builds a list of resources required
by a job. All such resource requests are considered as
absolutely essential for the job to commence. If the
\fB\-soft\fP option (see below) is encountered during the scan
then all following resources are designated as "soft
requirements" for execution, or "nice-to-have, but not
essential". If the \fB\-hard\fP flag is encountered at a later
stage of the scan, all resource requests following it once
again become "essential". The \fB\-hard\fP and \fB\-soft\fP
options in effect act as "toggles" during the scan.
.sp 1
If this option or a corresponding value in \fIqmon\fP is specified then
the corresponding \fB\-q\fP and \fB\-l\fP resource requirements will be
passed to defined JSV instances as parameter with the names \fBq_hard\fP and
\fBl_hard\fP. Find for information in the sections describing \fB\-q\fP and \fB\-l\fP.
(see \fB\-jsv\fP option below or find more information concerning JSV in
.M jsv 1 )
.
.\"
.IP "\fB\-h | \-h {u|s|o|n|U|O|S}...\fP"
Available for \fIqsub\fP (only \fB\-h\fP), \fIqrsh\fP, \fIqalter\fP
and \fIqresub\fP (hold state is removed when not set explicitly).
.sp 1
List of holds to place on a job, a task or some tasks of a job.
.sp 1
.nf
.ta \w'|u|  'u
`u'	denotes a user hold.
`s'	denotes a system hold.
`o'	denotes a operator hold.
`n'	denotes no hold (requires manager privileges).
.fi
.sp 1
As long as any hold other than `n' is assigned to the job
the job is not eligible for execution. Holds can be released
via
.I qalter
and
.M qrls 1 .
In case of
.I qalter
this is supported by the following additional option specifiers for 
the
.B \-h
switch:
.sp 1
.nf
.ta \w'|U|  'u
`U'	removes a user hold.
`S'	removes a system hold.
`O'	removes a operator hold.
.fi
.sp 1
xxQS_NAMExx managers can assign and remove all hold types, xxQS_NAMExx 
operators can assign and remove user and operator holds, and users can 
only assign or remove user holds.
.sp 1
In the case of
.I qsub
only user holds can be placed on a job and thus only the first
form of the option with the \fB\-h\fP switch alone is allowed.
As opposed to this,
.I qalter
requires the second form described above.
.sp 1
An alternate means to assign hold is provided by the
.M qhold 1
facility.
.sp 1
If the job is a array job (see the \fB\-t\fP option below), all tasks
specified via \fB\-t\fP are affected by the \fB\-h\fP operation
simultaneously.
.sp 1
.I Qalter
allows changing this option even while the job executes. The modified
parameter will only be in effect after a restart or migration of the job,
however.
.sp 1
If this option is specified with \fIqsub\fP or during the submission of a job in
\fIqmon\fP then the parameter \fBh\fP with the value \fBu\fP will be passed to the 
defined JSV instances indicating that the job will be in user hold after the 
submission finishes. 
(see \fB\-jsv\fP option below or find more information concerning JSV in
.M jsv 1 )
.
.\"
.IP "\fB\-help\fP"
Prints  a listing of all options.
.\"
.IP "\fB\-hold_jid wc_job_list\fP"
Available for \fIqsub\fP, \fIqrsh\fP, and \fIqalter\fP only. See 
.M sge_types 1 . 
for \fBwc_job_list\fP definition.
.sp 1
Defines or redefines the job dependency list of the submitted job. A 
reference by job name or pattern is only accepted if the 
referenced job is owned by the same user as the referring job. The 
submitted job is not eligible for execution unless all jobs 
referenced in the comma-separated job id and/or job name list have 
completed.  If any of the referenced jobs exits with exit code 100, the
submitted job will remain ineligible for execution.
.sp 1
With the help of job names or regular pattern one can specify
a job dependency on multiple jobs satisfying the regular pattern
or on all jobs with the requested name. The name dependencies are
resolved at submit time and can only be changed via qalter. New
jobs or name changes of other jobs will not be taken into account.
.sp 1
.I Qalter
allows changing this option even while the job executes. The modified
parameter will only be in effect after a restart or migration of the job,
however.
.sp 1
If this option or a corresponding value in \fIqmon\fP is specified then
this value will be passed to defined JSV
instances as parameter with the name \fBhold_jid\fP.
(see \fB\-jsv\fP option below or find more information concerning JSV in
.M jsv 1 )
.
.\"
.IP "\fB\-hold_jid_ad wc_job_list\fP"
Available for \fIqsub\fP, \fIqrsh\fP, and \fIqalter\fP only. See 
.M sge_types 1 . 
for \fBwc_job_list\fP definition.
.sp 1
Defines or redefines the job array dependency list of the submitted job. A 
reference by job name or pattern is only accepted if the 
referenced job is owned by the same user as the referring job. Each sub-task of the 
submitted job is not eligible for execution unless the corresponding sub-tasks 
of all jobs referenced in the comma-separated job id and/or job name list have 
completed.  If any array task of the referenced jobs exits with exit code 100, the
dependent tasks of the submitted job will remain ineligible for execution.
.sp 1
With the help of job names or regular pattern one can specify
a job dependency on multiple jobs satisfying the regular pattern
or on all jobs with the requested name. The name dependencies are
resolved at submit time and can only be changed via qalter. New
jobs or name changes of other jobs will not be taken into account.
.sp 1
If either the submitted job or any job in wc_job_list are not array
jobs with the same range of sub-tasks (see \fB\-t\fP option below), the request list will be
rejected and the job create or modify operation will error.
.sp 1
.I qalter
allows changing this option even while the job executes. The modified
parameter will only be in effect after a restart or migration of the job,
however.
.sp 1
If this option or a corresponding value in \fIqmon\fP is specified then
this value will be passed to defined JSV
instances as parameter with the name \fBhold_jid_ad\fP.
(see \fB\-jsv\fP option below or find more information concerning JSV in
.M jsv 1 )
.
.\"
.IP "\fB\-i [[hostname]:]file,...\fP"
Available for \fIqsub\fP, and \fIqalter\fP only.
.sp 1
Defines or redefines the file used for the standard input stream of
the job. If the \fIfile\fP constitutes an absolute filename, the input-path
attribute of the job is set to \fBpath\fP, including
the \fBhostname\fP. If the path name is relative, xxQS_NAMExx
expands \fBpath\fP either with the current working directory
path (if the \fB\-cwd\fP switch (see above) is also
specified) or with the home directory path. If 
\fBhostname\fP is present, the standard input stream will be
placed in the corresponding location only if the job runs on
the specified host. If the path contains a ":" without a
\fBhostname\fP, a leading ":" has to be specified.
.sp 1
By default /dev/null is the input stream for the job.
.sp 1
It is possible to use certain pseudo variables, whose values will be
expanded at runtime of the job and will be used to express the
standard input stream as described in the \fI-e\fP option for the standard
error stream.
.sp 1
.I Qalter
allows changing this option even while the job executes. The
modified parameter will only be in effect after a restart or migration
of the job, however.
.sp 1
If this option or a corresponding value in \fIqmon\fP is specified then
this value will be passed to defined JSV
instances as parameter with the name \fBi\fP.
(see \fB\-jsv\fP option below or find more information concerning JSV in
.M jsv 1 )
.\"
.IP "\fB\-inherit\fP"
Available only for \fIqrsh\fP and
.M qmake 1 .
.sp 1
.I qrsh 
allows the user to start a task in an already scheduled parallel job.
The option \fB\-inherit\fP tells 
.I qrsh
to read a job id from the environment variable JOB_ID and start the 
specified command as a task in this job. Please note that in this case,
the hostname of the host where the command will be executed must precede 
the command to execute; the syntax changes to
.sp 1
.B qrsh \-inherit
[
.B other options
] 
.B hostname command 
[ 
.B command_args 
]
.sp 1
Note also, that in combination with \fB\-inherit\fP, most other command
line options will be ignored.
Only the options \fB\-verbose\fP, \fB\-v\fP and \fB\-V\fP 
will be interpreted. 
As a replacement to option \fB\-cwd\fP please use \fB\-v PWD\fP.
.sp 1
Usually a task should have the same environment (including the current 
working directory) as the corresponding job, so specifying the option
\fB\-V\fP should be suitable for most applications.
.sp 1
\fINote:\fP If in your system the qmaster tcp port is not configured as a
service, but rather via the environment
variable xxQS_NAME_Sxx_QMASTER_PORT, make sure that this variable is set in the environment when
calling
.I qrsh
or
.I qmake
with the \fB\-inherit\fP option. If you call
.I qrsh
or
.I qmake
with the \fB\-inherit\fP
option from within a job script, export xxQS_NAME_Sxx_QMASTER_PORT with the 
option "-v xxQS_NAME_Sxx_QMASTER_PORT" either as a command argument or an
embedded directive.
.sp 1
This parameter is not available in the JSV context.
(see \fB\-jsv\fP option below or find more information concerning JSV in
.M jsv 1 )

.\"
.IP "\fB\-j y[es]|n[o]\fP"
Available for \fIqsub\fP, \fIqsh\fP, \fIqrsh\fP, \fIqlogin\fP and
\fIqalter\fP only.
.sp 1
Specifies whether or not the standard error stream of the job
is merged into the standard output stream.
.br
If both the \fB\-j y\fP and the \fB\-e\fP options are present,
xxQS_NAMExx sets but ignores the error-path attribute.
.sp 1
.I Qalter
allows changing this option even while the job executes. The modified
parameter will only be in effect after a restart or migration of the job,
however.
.sp 1
The value specified with this option or the corresponding value specified in
\fIqmon\fP will only be passed to defined JSV instances if the value is \fIyes\fP.
The name of the parameter will be \fBj\fP. The value will be \fBy\fP also
when then long form \fByes\fP was specified during submission.
(see \fB\-jsv\fP option below or find more information concerning JSV in
.M jsv 1 )
.
.\"
.IP "\fB\-js job_share\fP"
Available for \fIqsub\fP, \fIqsh\fP, \fIqrsh\fP, \fIqlogin\fP and
\fIqalter\fP only.
.sp 1
Defines or redefines the job share of the job relative to other jobs.
Job share is an unsigned integer value.
The default job share value for jobs is 0.
.sp 1
The job share influences the Share Tree Policy and the Functional
Policy. It has no effect on the Urgency and Override Policies (see
.M share_tree 5 ,
.M sched_conf 5
and the
.I "xxQS_NAMExx Installation and Administration Guide"
for further information on the resource management policies supported by xxQS_NAMExx).
.sp 1
In case of the Share Tree Policy, users can distribute the tickets to
which they are currently entitled among their jobs using different
shares assigned via \fB\-js\fP. If all jobs have the same job share
value, the tickets are distributed evenly. Otherwise, jobs receive tickets
relative to the different job shares. Job shares are treated like
an additional level in the share tree in the latter case.
.sp 1
In connection with the Functional Policy, the job share can be used to
weight jobs within the functional job category.
Tickets are distributed relative to any
uneven job share distribution treated as a virtual share distribution level
underneath the functional job category.
.sp 1
If both the Share Tree and the Functional Policy are active, the job
shares will have an effect in both policies, and the tickets
independently derived in each of them are added to the total number of
tickets for each job.
.sp 1
If this option or a corresponding value in \fIqmon\fP is specified then
this value will be passed to defined JSV
instances as parameter with the name \fBjs\fP.
(see \fB\-jsv\fP option below or find more information concerning JSV in
.M jsv 1 )
.\"
.IP "\fB\-jsv jsv_url\fP"
Available for \fIqsub\fP, \fIqsh\fP, \fIqrsh\fP and \fIqlogin\fP only.
.sp 1
Defines a client JSV instance which will be executed to verify the
job specification before the job is sent to qmaster. 
.sp 1
In contrast to other options this switch will not be overwritten 
if it is also used in sge_request files. Instead all specified JSV
instances will be executed to verify the job to be submitted.
.sp 1
The JSV instance which is directly passed with the command-line of a client
is executed as first to verify the job specification. After that the JSV
instance which might have been defined in various sge_request files will
be triggered to check the job. Find more details in man page 
.M jsv 1 
and 
.M sge_request 5 .
.sp 1
The syntax of the \fBjsv_url\fP is specified in 
.M sge_types(1).
.\"
.IP "\fB\-l resource=value\fP,..."
Available for \fIqsub\fP, \fIqsh\fP, \fIqrsh\fP, \fIqlogin\fP and
\fIqalter\fP only.
.sp 1
Launch the job in a xxQS_NAMExx queue meeting the given resource request list.
In case of
.I qalter
the previous definition is replaced by the specified one.
.sp 1
.M complex 5
describes how a list of available resources and their
associated valid value specifiers can be obtained.
.sp 1
There may be multiple \fB\-l\fP switches in a single
command. You may request multiple \fB\-l\fP options to be
soft or hard both in the same command line. In case of a
serial job multiple \fB\-l\fP switches refine the definition
for the sought queue.
.sp 1
.I Qalter
allows changing the value of this option even while the job is running, but only if the 
initial list of resources does not contain a resource that
is marked as consumable. However the modification will only be  
effective after a restart or migration of the job.
.sp 1
If this option or a corresponding value in \fIqmon\fP is specified 
the these hard and soft resource requirements will be
passed to defined JSV instances as parameter with the names \fBl_hard\fP and
\fBl_soft\fP. If regular expressions will be used for resource requests,
then these expressions will be passed as they are. Also shortcut names
will not be expanded.
(see \fB\-jsv\fP option above or find more information concerning JSV in
.M jsv 1 )
.
.\"
.IP "\fB\-m b|e|a|s|n,...\fP"
Available for \fIqsub\fP, \fIqsh\fP, \fIqrsh\fP, \fIqlogin\fP and
\fIqalter\fP only.
.sp 1
Defines or redefines under which circumstances mail is to be sent
to the job owner or to the users defined with the
\fB\-M\fP option described below. The option arguments
have the following meaning:
.sp 1
.nf
.ta \w'|b|  'u
`b'     Mail is sent at the beginning of the job.
`e'     Mail is sent at the end of the job.
`a'     Mail is sent when the job is aborted or 
        rescheduled.
`s'     Mail is sent when the job is suspended.
`n'     No mail is sent.
.fi
.sp 1
Currently no mail is sent when a job is suspended.
.sp 1
.I Qalter
allows changing the b, e, and a option arguments even while the job
executes. The modification of the b option argument will only be in
effect after a restart or migration of the job, however.
.sp 1
If this option or a corresponding value in \fIqmon\fP is specified then
this value will be passed to defined JSV
instances as parameter with the name \fBm\fP.
(see \fB\-jsv\fP option above or find more information concerning JSV in
.\"
.IP "\fB\-M user[@host],...\fP"
Available for \fIqsub\fP, \fIqsh\fP, \fIqrsh\fP, \fIqlogin\fP and
\fIqalter\fP only.
.sp 1
Defines or redefines the list of users to which the server that executes
the job has to send mail, if the server sends mail about the job.
Default is the job owner at the originating host.
.sp 1
.I Qalter
allows changing this option even while the job executes.
.sp 1
If this option or a corresponding value in \fIqmon\fP is specified then
this value will be passed to defined JSV
instances as parameter with the name \fBM\fP.
(see \fB\-jsv\fP option above or find more information concerning JSV in
.M jsv 1 )
.
.\"
.IP "\fB\-masterq wc_queue_list\fP"
Available for \fIqsub\fP, \fIqrsh\fP, \fIqsh\fP, \fIqlogin\fP and \fIqalter\fP.
Only meaningful for parallel jobs, i.e. together with the -pe option.
.sp 1
Defines or redefines a list of cluster queues, queue domains and queue 
instances which may be used to become the so called
.I master queue
of this parallel job. A more detailed description of \fIwc_queue_list\fP 
can be found in
.M sge_types 1 .
The
.I master queue
is defined as
the queue where the parallel job is started. The other queues to which the
parallel job spawns tasks are called \fIslave queues\fP.
A parallel job only has one \fImaster queue\fP.
.sp 1
This parameter has all the properties of a resource request and will be
merged with requirements derived from the \fB\-l\fP option described above.
.sp 1
.I Qalter
allows changing this option even while the job executes. The
modified parameter will only be in effect after a restart or migration of
the job, however.
.sp 1
If this option or a corresponding value in \fIqmon\fP is specified 
the this hard resource requirement will be passed to defined JSV 
instances as parameter with the name \fBmasterq\fP. 
(see \fB\-jsv\fP option above or find more information concerning JSV in
.M jsv 1 )
.
.\"
.IP "\fB\-notify\fP"
Available for \fIqsub\fP, \fIqrsh\fP (with command) and
\fIqalter\fP only.
.sp 1
This flag,
when set causes xxQS_NAMExx to send "warning" signals
to a running job prior to sending the signals themselves. If
a SIGSTOP is pending, the job will receive a SIGUSR1 several
seconds before the SIGSTOP. If a SIGKILL is pending, the job
will receive a SIGUSR2 several seconds before the SIGKILL.
This option provides the running job, before receiving the SIGSTOP 
or SIGKILL, a configured time interval to do e.g. cleanup operations.  
The amount of time delay is controlled by the \fBnotify\fP
parameter in each queue configuration (see
.M queue_conf 5 ).
.sp 1
Note that the Linux operating system "misused" the user signals SIGUSR1
and SIGUSR2 in some early Posix thread implementations. You might not want
to use the \fB\-notify\fP option if you are running multi-threaded applications
in your jobs under Linux, particularly on 2.0 or earlier kernels.
.sp 1
.I Qalter
allows changing this option even while the job executes.
.sp 1
Only if this option is used the parameter named \fBnotify\fP with the value
\fBy\fP will be passed to defined JSV instances. 
(see \fB\-jsv\fP option above or find more information concerning JSV in
.M jsv 1 )
.
.\"
.IP "\fB\-now y[es]|n[o]\fP"                        
Available for \fIqsub\fP, \fIqsh\fP, \fIqlogin\fP and \fIqrsh\fP.
.sp 1
\fB\-now y\fP
tries to start the job immediately or 
not at all. The command returns 0 on success, or 1 on failure (also if
the job could not be scheduled immediately).  For array jobs submitted with the
\fB-now\fP option, if all tasks cannot be immediately scheduled, no tasks are
scheduled.
.sp 1
Jobs submitted with \fB\-now y\fP option, can ONLY run on INTERACTIVE queues.
\fB\-now y\fP is default for \fIqsh\fP, \fIqlogin\fP and \fIqrsh\fP
.sp 1
With the \fB\-now n\fP option, the job will be put into the pending queue if it
cannot be executed immediately. \fB\-now n\fP is default for \fIqsub\fP.
.sp 1
The value specified with this option or the corresponding value specified in
\fIqmon\fP will only be passed to defined JSV instances if the value is \fIyes\fP.
The name of the parameter will be \fBnow\fP. The value will be \fBy\fP also
when then long form \fByes\fP was specified during submission.
(see \fB\-jsv\fP option above or find more information concerning JSV in
.M jsv 1 )
.
.\"
.IP "\fB\-N name\fP"
Available for \fIqsub\fP, \fIqsh\fP, \fIqrsh\fP, \fIqlogin\fP and
\fIqalter\fP only.
.sp 1
The name of the job. The name should follow the "\fBname\fP" definition in
.M sge_types 1 .
Invalid job names will be denied at submit time.
.sp 1
If the \fB\-N\fP option is not present, xxQS_NAMExx assigns
the name of the job script to the job after 
any directory pathname has been removed from the
script-name. If the script is read from standard
input, the job name defaults to STDIN.
.sp 1
In the case of
.I qsh
or
.I qlogin
with the \fB\-N\fP option is absent, the string `INTERACT' is 
assigned to the job.
.sp 1
In the case of 
.I qrsh
if the \fB\-N\fP option is absent, the resulting job name is determined from 
the qrsh command line by using the argument string up to the first occurrence 
of a semicolon or whitespace and removing the directory pathname.
.sp 1
.I Qalter
allows changing this option even while the job executes.
.sp 1
The value specified with this option or the corresponding value specified in
\fIqmon\fP will be passed to defined JSV instances as parameter with the name
\fIN\fP. 
(see \fB\-jsv\fP option above or find more information concerning JSV in
.M jsv 1 )
.
.\"
.IP "\fB\-noshell\fP"
Available only for \fIqrsh\fP with a command line.
.sp 1
Do not start the command line given to \fIqrsh\fP in a user's login shell, i.e.
execute it without the wrapping shell.
.sp 1
This option can be used to speed up execution as some overhead, like the  
shell startup and sourcing the shell resource files, is avoided.
.sp 1
This option can only be used if no shell-specific command line parsing is
required. If the command line contains shell syntax like environment
variable substitution or (back) quoting, a shell must be started.
In this case, either do not use the \fB\-noshell\fP option or include
the shell call in the command line.
.sp 1
Example:
.br 
qrsh echo '$HOSTNAME'
.br 
Alternative call with the -noshell option
.br 
qrsh -noshell /bin/tcsh -f -c 'echo $HOSTNAME'
.\"
.IP "\fB\-nostdin\fP"
Available only for \fIqrsh\fP.
.sp 1
Suppress the input stream STDIN - \fIqrsh\fP will pass the option -n to 
the
.M rsh 1
command. This is especially useful, if multiple tasks
are executed in parallel using \fIqrsh\fP, e.g. in a
.M make 1
process - it would be undefined, which process would get the input.
.\"
.IP "\fB\-o [[hostname]:]path,...\fP"
Available for \fIqsub\fP, \fIqsh\fP, \fIqrsh\fP, \fIqlogin\fP and
\fIqalter\fP only.
.sp 1
The path used for the standard output stream of the job. The
\fBpath\fP is handled as described in the \fB\-e\fP option for
the standard error stream.
.sp 1
By default the file name for standard
output has the form \fIjob_name.\fPo\fIjob_id\fP and
\fIjob_name.\fPo\fIjob_id\fP.\fBtask_id\fP for array job tasks (see
\fB\-t\fP option below).
.sp 1
.I Qalter
allows changing this option even while the job executes. The modified
parameter will only be in effect after a restart or migration of the job,
however.
.sp 1
If this option or a corresponding value in \fIqmon\fP is specified then
this value will be passed to defined JSV
instances as parameter with the name \fBo\fP.
(see \fB\-jsv\fP option above or find more information concerning JSV in
.M jsv 1 )
.
.\"
.IP "\fB\-ot override_tickets\fP"
Available for \fIqalter\fP only.
.sp 1
Changes the number of override tickets for the specified job.
Requires manager/operator privileges.
.\"
.IP "\fB\-P project_name\fP"
Available for \fIqsub\fP, \fIqsh\fP, \fIqrsh\fP, \fIqlogin\fP and
\fIqalter\fP only.
.sp 1
Specifies the project to which this job is assigned. The administrator
needs to give permission to individual users to submit jobs to a
specific project. (see \fB\-aprj\fP option to
.M qconf 1 ).
.sp 1
If this option or a corresponding value in \fIqmon\fP is specified then
this value will be passed to defined JSV
instances as parameter with the name \fBot\fP.
(see \fB\-jsv\fP option above or find more information concerning JSV in
.M jsv 1 )
.
.\"
.IP "\fB\-p priority\fP"
Available for \fIqsub\fP, \fIqsh\fP, \fIqrsh\fP, \fIqlogin\fP and
\fIqalter\fP only.
.sp 1
Defines or redefines the priority of the job relative to other jobs.
Priority is an integer in the range -1023 to 1024.
The default priority value for jobs is 0.
.sp 1
Users may only decrease the priority of their jobs.
xxQS_NAMExx managers and administrators may also increase the priority
associated with jobs. If a pending job has higher priority, it is
earlier eligible for being dispatched by the xxQS_NAMExx scheduler.
.sp 1
If this option or a corresponding value in \fIqmon\fP is specified and
the priority is not 0 then this value will be passed to defined JSV
instances as parameter with the name \fBp\fP.
(see \fB\-jsv\fP option above or find more information concerning JSV in
.M jsv 1 )
.
.\"
.IP "\fB\-pe parallel_environment \fBn\fP[\fB-\fP[\fBm\fP]]|[\fB-\fP]\fBm\fP,...\fP"
Available for \fIqsub\fP, \fIqsh\fP, \fIqrsh\fP, \fIqlogin\fP and
\fIqalter\fP only.
.sp 1
Parallel programming environment (PE) to instantiate. For more detail about PEs,
please see the
.M sge_types 1 .
.sp 1
.I Qalter
allows changing this option even while the job executes. The modified
parameter will only be in effect after a restart or migration of the job,
however.
.sp 1
If this option or a corresponding value in \fIqmon\fP is specified then
the parameters \fBpe_name\fP, \fBpe_min\fP and \fBpe_max\fP will be passed to configured
JSV instances where \fBpe_name\fP will be the name of the parallel environment
and the values \fBpe_min\fP and \fBpe_max\fP represent the values n and m which
have been provided with the \fB-pe\fP option. A missing specification of m
will be expanded as value 9999999 in JSV scripts and it represents the value infinity.
(see \fB\-jsv\fP option above or find more information concerning JSV in
.M jsv 1 )
.
.\"
.IP "\fB\-pty y[es]|n[o]\fP"
Available for \fIqrsh\fP and \fIqlogin\fP only.
.sp 1
-pty yes enforces the job to be started in a pseudo terminal (pty). If no pty is 
available, the job start fails.
-pty no
enforces the job to be started without a pty.
By default,
.I qrsh without a command
and
.I qlogin
start the job in a pty,
.I qrsh with a command
starts the job without a pty.
.sp 1
This parameter is not available in the JSV context.
(see \fB\-jsv\fP option above or find more information concerning JSV in
.M jsv 1 )
.\"
.IP "\fB\-q wc_queue_list\fP"
Available for \fIqsub\fP, \fIqrsh\fP, \fIqsh\fP, \fIqlogin\fP and \fIqalter\fP.
.sp 1
Defines or redefines a list of cluster queues, queue domains or queue
instances which may be used to execute this job. Please find a description
of \fIwc_queue_list\fP in
.M sge_types 1 .
This parameter has all the properties of a resource request and
will be merged with requirements derived from the \fB\-l\fP option
described above.
.sp 1
.I Qalter
allows changing this option even while the job executes. The modified
parameter will only be in effect after a restart or migration of the job,
however.
.sp 1
If this option or a corresponding value in \fIqmon\fP is specified 
the these hard and soft resource requirements will be
passed to defined JSV instances as parameters with the names \fBq_hard\fP and
\fBq_soft\fP. If regular expressions will be used for resource requests,
then these expressions will be passed as they are. Also shortcut names
will not be expanded.
(see \fB\-jsv\fP option above or find more information concerning JSV in
.M jsv 1 )
.
.\"
.IP "\fB\-R y[es]|n[o]\fP"
Available for \fIqsub\fP, \fIqrsh\fP, \fIqsh\fP, \fIqlogin\fP and \fIqalter\fP.
.sp 1
Indicates whether a reservation for this job should be done. Reservation 
is never done for immediate jobs, i.e. jobs submitted using the \fB\-now yes\fP
option.  Please note that regardless of the reservation request,
job reservation might be disabled using max_reservation in 
.M sched_conf 5
and might be limited only to a certain number of high priority jobs.
.sp 1
By default jobs are submitted with the \fB\-R n\fP option.
.sp 1
The value specified with this option or the corresponding value specified in
\fIqmon\fP will only be passed to defined JSV instances if the value is \fIyes\fP.
The name of the parameter will be \fBR\fP. The value will be \fBy\fP also
when then long form \fByes\fP was specified during submission.
(see \fB\-jsv\fP option above or find more information concerning JSV in
.M jsv 1 )
.
.\"
.IP "\fB\-r y[es]|n[o]\fP"
Available for \fIqsub\fP and \fIqalter\fP only.
.sp 1
Identifies the ability of a job to be rerun or not.
If the value of \fB\-r\fP is 'yes', the job will be rerun if the job was aborted
without leaving a consistent exit state.
(This is typically the case if the node on which the job is running
crashes).
If \fB\-r\fP is 'no', the job will not be rerun under any circumstances.
.br
Interactive jobs submitted with
.I qsh,
.I qrsh
or
.I qlogin
are not rerunnable.
.sp 1
.I Qalter
allows changing this option even while the job executes.
.sp 1
The value specified with this option or the corresponding value specified in
\fIqmon\fP will only be passed to defined JSV instances if the value is \fIyes\fP.
The name of the parameter will be \fBr\fP. The value will be \fBy\fP also
when then long form \fByes\fP was specified during submission.
(see \fB\-jsv\fP option above or find more information concerning JSV in
.M jsv 1 )
.
.\"
.IP "\fB\-sc variable[=value],...\fP"
Available for \fIqsub\fP, \fIqsh\fP, \fIqrsh\fP, \fIqlogin\fP and
\fIqalter\fP only.
.sp 1
Sets the given name/value pairs as the job's context. \fBValue\fP may be
omitted. xxQS_NAMExx replaces the job's previously defined context with
the one given as the argument.
Multiple \fB\-ac\fP, \fB\-dc\fP, and \fB\-sc\fP options may be given.
The order is important.
.sp 1
Contexts provide a way to dynamically attach and remove meta-information
to and from a job. The context variables are \fBnot\fP passed to the job's
execution context in its environment.
.sp 1
.I Qalter
allows changing this option even while the job executes.
.sp 1
The outcome of the evaluation of all \fB\-ac\fP, \fB\-dc\fP, and \fB\-sc\fP
options or corresponding values in \fIqmon\fP is passed to defined JSV
instances as parameter with the name \fB\aac\fP.
(see \fB\-jsv\fP option above or find more information concerning JSV in
.M jsv 1 )
.
.\"
.IP "\fB\-shell y[es]|n[o]\fP"
Available only for \fIqsub\fP.
.sp 1
\fB\-shell n\fP
causes qsub to execute the command line directly, as if by
.M exec 2 .
No command shell will be executed for the job.  This option only applies when
\fB\-b y\fP is also used.  Without \fB\-b y\fP, \fB\-shell n\fP has no effect.
.sp 1
This option can be used to speed up execution as some overhead, like the  
shell startup and sourcing the shell resource files is avoided.
.sp 1
This option can only be used if no shell-specific command line parsing is
required. If the command line contains shell syntax, like environment
variable substitution or (back) quoting, a shell must be started.
In this case either do not use the \fB\-shell n\fP option or execute the shell
as the command line and pass the path to the executable as a parameter.
.sp 1
If a job executed with the \fB\-shell n\fP option fails due to a user error, such as an invalid
path to the executable, the job will enter the error state.
.sp 1
\fB\-shell y\fP cancels the effect of a previous \fB\-shell n\fP.
Otherwise, it has no effect.
.sp 1
See \fB\-b\fP and \fB\-noshell\fP for more information.
.sp 1
The value specified with this option or the corresponding value specified in
\fIqmon\fP will only be passed to defined JSV instances if the value is \fIyes\fP.
The name of the parameter will be \fBshell\fP. The value will be \fBy\fP also
when then long form \fByes\fP was specified during submission.
(see \fB\-jsv\fP option above or find more information concerning JSV in
.M jsv 1 )
.
.\"
.IP "\fB\-soft\fP"
Available for \fIqsub\fP, \fIqsh\fP, \fIqrsh\fP, \fIqlogin\fP and
\fIqalter\fP only.
.sp 1
Signifies that all resource requirements following in the
command line will be soft requirements and
are to be filled on an "as available" basis.
.br
As xxQS_NAMExx scans the command line and script file for xxQS_NAMExx
options and parameters, it builds a list of resources required
by the job. All such resource requests are considered as
absolutely essential for the job to commence. If the
\fB\-soft\fP option is encountered during the scan
then all following resources are designated as "soft
requirements" for execution, or "nice-to-have, but not
essential". If the \fB\-hard\fP flag (see above) is encountered at a later
stage of the scan, all resource requests following it once
again become "essential". The \fB\-hard\fP and \fB\-soft\fP
options in effect act as "toggles" during the scan.
.sp 1
If this option or a corresponding value in \fIqmon\fP is specified then
the corresponding \fB\-q\fP and \fB\-l\fP resource requirements will be
passed to defined JSV instances as parameter with the names \fBq_soft\fP and
\fBl_soft\fP. Find for information in the sections describing \fB\-q\fP and \fB\-l\fP.
(see \fB\-jsv\fP option above or find more information concerning JSV in
.M jsv 1 )
.
.\"
.IP "\fB\-sync y[es]|n[o]\fP"
Available for \fIqsub\fP.
.sp 1
\fB\-sync y\fP
causes
.I qsub
to wait for the job to complete before exiting.  If the job completes successfully,
.I qsub's
exit code will be that of the completed job.  If the job fails to complete
successfully,
.I qsub
will print out a error message indicating why the job failed and will have an
exit code of 1.  If
.I qsub
is interrupted, e.g. with CTRL-C, before the job completes, the job will be
canceled.
.br
With the \fB\-sync n\fP option,
.I qsub
will exit with an exit code of 0 as soon as the job is submitted successfully.
\fB\-sync n\fP is default for \fIqsub\fP.
.br
If \fB\-sync y\fP is used in conjunction with \fB\-now y\fP,
.I qsub
will behave as though only \fB\-now y\fP were given until the job has been
successfully scheduled, after which time
.I qsub
will behave as though only \fB\-sync y\fP were given.
.br
If \fB\-sync y\fP is used in conjunction with \fB\-t n[-m[:i]]\fP,
.I qsub
will wait for all the job's tasks to complete before exiting.  If all
the job's tasks complete successfully,
.I qsub's
exit code will be that of the first completed job tasks with a non-zero exit
code, or 0 if all job tasks exited with an exit code of 0.  If any of the job's
tasks fail to complete successfully,
.I qsub
will print out an error message indicating why the job task(s) failed and will
have an exit code of 1.  If
.I qsub
is interrupted, e.g. with CTRL-C, before the job completes, all of the job's
tasks will be canceled.
.sp 1
Information that this switch was specified during submission is not
available in the JSV context.
(see \fB\-jsv\fP option above or find more information concerning JSV in
.M jsv 1 )
.
.\"
.IP "\fB\-S [[hostname]:]pathname,...\fP"
Available for \fIqsub\fP, \fIqsh\fP and \fIqalter\fP.
.sp 1
Specifies the interpreting shell for the job. Only one \fBpathname\fP
component without a \fBhost\fP specifier is valid and only one path name
for a given host is allowed. Shell paths with host
assignments define the interpreting shell for the job if the host is the
execution host. The shell path without host specification is used if the
execution host matches none of the hosts in the list.
.sp 1
Furthermore, the pathname can be constructed with pseudo environment
variables as described for the \fB\-e\fP option above.
.sp 1
In the case of
.I qsh
the specified shell path is used to execute the 
corresponding command interpreter in the
.M xterm 1
(via its \fI\-e\fP option) 
started on behalf of the interactive job. 
.I Qalter
allows changing this option even while the job executes. The modified
parameter will only be in effect after a restart or migration of the job,
however.
.sp 1
If this option or a corresponding value in \fIqmon\fP is specified then
this value will be passed to defined JSV
instances as parameter with the name \fBS\fP.
(see \fB\-jsv\fP option above or find more information concerning JSV in
.M jsv 1 )
.
.\"
.IP "\fB\-t n[-m[:s]]\fP"
Available for \fIqsub\fP and \fIqalter\fP only.
.sp 1
Submits a so called \fIArray Job\fP, i.e. an array of identical tasks being
differentiated only by an index number and being treated by xxQS_NAMExx
almost like a series of jobs. The option argument to \fB\-t\fP specifies
the number of array job tasks and the index number which will be associated
with the tasks. The index numbers will be exported to the job tasks via the
environment variable \fBxxQS_NAME_Sxx_TASK_ID\fP. The option arguments n, m and s will be available through the environment variables \fBxxQS_NAME_Sxx_TASK_FIRST\fP, \fBxxQS_NAME_Sxx_TASK_LAST\fP and  \fBxxQS_NAME_Sxx_TASK_STEPSIZE\fP.
.sp 1
.nf
.RS
Following restrictions apply to the values n and m:
.sp 1
.RS
1 <= n <= MIN(2^31-1, max_aj_tasks)
1 <= m <= MIN(2^31-1, max_aj_tasks)
n <= m
.RE
.fi
.sp 1
\fImax_aj_tasks\fP is defined in the cluster configuration (see 
.M sge_conf 5)
.sp 1
The task id range specified in the option argument
may be a single number, a simple range of the form
n-m or a range with a step size. Hence, the task id range specified by
2-10:2 would result in the task id indexes 2, 4, 6, 8, and 10,
for a total of 5 identical tasks, each with the environment variable
xxQS_NAME_Sxx_TASK_ID containing one of the 5 index numbers.
.sp 1
All array job tasks inherit the same resource requests and attribute
definitions as specified in the \fIqsub\fP or \fIqalter\fP command line,
except for the \fB\-t\fP option. The tasks are scheduled independently and,
provided enough resources exist, concurrently, very much like separate jobs.
However, an array job or a sub-array there of can be accessed as a single unit
by commands like
.M qmod 1
or
.M qdel 1 .
See the corresponding manual pages for further detail.
.sp 1
Array jobs are commonly used to execute the same type of operation on
varying input data sets correlated with the task index number. The number
of tasks in a array job is unlimited.
.sp 1
STDOUT and STDERR of array job tasks will be written into different files
with the default location
.sp 1
.nf
<jobname>.['e'|'o']<job_id>'.'<task_id>
.fi
.sp 1
In order to change this default, the \fB\-e\fP and \fB\-o\fP options (see
above) can be used together with the pseudo environment variables $HOME,
$USER, $JOB_ID, $JOB_NAME, $HOSTNAME, and $xxQS_NAME_Sxx_TASK_ID.
.sp 1
Note, that you can use the output redirection to divert the output of all
tasks into the same file, but the result of this is undefined.
.sp 1
If this option or a corresponding value in \fIqmon\fP is specified then
this value will be passed to defined JSV instances as parameters 
with the name \fBt_min\fP, \fBt_max\fP and \fBt_step\fP
(see \fB\-jsv\fP option above or find more information concerning JSV in
.M jsv 1 )
.
.\"
.\" Empty .SH required below to fix man indentation bug
.SH
.\"
.IP "\fB\-tc max_running_tasks\fP"
Available for \fIqsub\fP and \fIqalter\fP only.
.sp 1
Can be used in conjunction with array jobs (see -t option) to set a
self-imposed limit on the maximum number of concurrently running tasks
per job.
.sp 1
If this option or a corresponding value in qmon is specified
then  this  value will be passed to defined JSV instances as
parameter with the name \fBtc\fP. (see \fB\-jsv\fP option above or find more information concerning JSV in
.M jsv 1 )
.\"
.IP "\fB\-terse\fP"
Available for \fIqsub\fP only.
.sp 1
-terse causes the \fIqsub\fP to display only the job-id of the job being
submitted rather than the regular "Your job ..." string.
In case of an error the error is reported on stderr as usual.
.br
This can be helpful for scripts which need to parse \fIqsub\fP output to get
the job-id.
.sp 1
Information that this switch was specified during submission is not
available in the JSV context.
(see \fB\-jsv\fP option above or find more information concerning JSV in
.M jsv 1 )
.
.\"
.IP "\fB\-u username,...\fP"
Available for \fIqalter\fP only. Changes are only made on those
jobs which were submitted by users specified in the list
of usernames.
For managers it is possible to use the \fB\qalter -u '*'\fP command
to modify all jobs of all users.
.sp 1
If you use the \fB\-u\fP switch it is not permitted to
specify an additional \fIwc_job_range_list\fP.
.\"
.IP "\fB\-v variable[=value],...\fP"
Available for \fIqsub\fP, \fIqrsh\fP (with command argument) and \fIqalter\fP.
.sp 1
Defines or redefines the environment variables to
be exported to the execution context of the job.
If the \fB\-v\fP option is present xxQS_NAMExx will add
the environment variables defined as arguments to the switch and,
optionally, values of specified variables, to the execution context of
the job.
.sp 1
.I Qalter
allows changing this option even while the job executes. The modified
parameter will only be in effect after a restart or migration of the job,
however.
.sp 1
All environment variables specified with \fB\-v\fP, \fB\-V\fP or the
DISPLAY variable provided with \fB\-display\fP will be exported to the
defined JSV instances only optionally when this is requested explicitly
during the job submission verification.
(see \fB\-jsv\fP option above or find more information concerning JSV in
.M jsv 1 )
.
.\"
.IP "\fB\-verbose\fP"
Available only for \fIqrsh\fP and
.M qmake 1 .
.sp 1
Unlike \fIqsh\fP and \fIqlogin\fP, \fIqrsh\fP does not output any 
informational messages while establishing the session, compliant
with the standard
.M rsh 1
and
.M rlogin 1
system calls.
If the option \fB-verbose\fP is set, \fIqrsh\fP behaves like
the \fIqsh\fP and \fIqlogin\fP commands, printing information about 
the process of establishing the
.M rsh 1
or
.M rlogin 1
session.
.\"
.IP "\fB\-verify\fP"
Available for \fIqsub\fP, \fIqsh\fP, \fIqrsh\fP, \fIqlogin\fP and \fIqalter\fP.
.sp 1
Instead of submitting a job, prints detailed information about the would-be job
as though
.M qstat 1
-j were used, including the effects of command-line parameters and the external 
environment.
.\"
.IP "\fB\-V\fP"
Available for \fIqsub\fP, \fIqsh\fP, \fIqrsh with command\fP and \fIqalter\fP.
.sp 1
Specifies that all environment variables active within the
.I qsub
utility be exported to the context of the job.
.sp 1
All environment variables specified with \fB\-v\fP, \fB\-V\fP or the
DISPLAY variable provided with \fB\-display\fP will be exported to the
defined JSV instances only optionally when this is requested explicitly
during the job submission verification.
(see \fB\-jsv\fP option above or find more information concerning JSV in
.M jsv 1 )
.
.\"
.IP "\fB\-w e\fP|\fBw\fP|\fBn\fP|\fBp\fP|\fBv\fP"
Available for \fIqsub\fP, \fIqsh\fP, \fIqrsh\fP, \fIqlogin\fP and \fIqalter\fP.
.sp 1
Specifies a validation level applied to the job to be submitted
(\fIqsub\fP, \fIqlogin\fP,
and \fIqsh\fP) or the specified queued job (\fIqalter\fP).
The information displayed 
indicates whether the job can possibly be scheduled assuming an empty 
system with no other jobs. Resource requests exceeding the configured 
maximal thresholds or requesting unavailable resource attributes are  
possible causes for jobs to fail this validation.
.sp 1
The specifiers e, w, n and v define the following validation modes:
.sp 1
.nf
.ta \w'|b|  'u
`e'	error - jobs with invalid requests will be
	rejected.
`w'	warning - only a warning will be displayed
	for invalid requests.
`n'	none - switches off validation; the default for
	\fIqsub\fP, \fIqalter\fP, \fIqrsh\fP, \fIqsh\fP
	and \fIqlogin\fP.
`p'	poke - does not submit the job but prints a 
     validation report based on a cluster as is with 
     all resource utilizations in place.
`v'	verify - does not submit the job but prints a
     validation report based on an empty cluster.
.fi
.sp 1
Note, that the necessary checks are performance consuming and hence the 
checking is switched off by default.
It should also be noted that load values are not taken into account with 
the verification since they are assumed to be too volatile. To cause -w e 
verification to be passed at submission time, it is possible to specify 
non-volatile values (non-consumables) or maximum values (consumables) in 
complex_values.
.IP "\fB\-wd working_dir\fP"
Available for \fIqsub\fP, \fIqsh\fP, \fIqrsh\fP and
\fIqalter\fP only.
.sp 1
Execute the job from the directory specified in working_dir.
This switch will activate xxQS_NAMExx's path aliasing facility, if the
corresponding
configuration files are present (see
.M xxqs_name_sxx_aliases 5 ).
.sp 1
.I Qalter
allows changing this option even while the job executes. The modified
parameter will only be in effect after a restart or migration of the job,
however.
The parameter value will be available in defined JSV instances as parameter
with the name \fBcwd\fP
(see \fB-cwd\fP switch above or find more information concerning JSV in
.M jsv 1 )
.
.\"       
.IP "\fBcommand\fP"
Available for \fIqsub\fP and \fIqrsh\fP only.
.sp 1
The job's scriptfile or binary.
If not present or if the operand is the 
single-character string '-',
.I qsub
reads the script from standard input.
.sp 1
The command will be available in defined JSV instances as parameter
with the name \fBCMDNAME\fP
(see \fB\-jsv\fP option above or find more information concerning JSV in
.M jsv 1 )
.
.\"
.IP "\fBcommand_args\fP"
Available for \fIqsub\fP, \fIqrsh\fP and \fIqalter\fP only.
.sp 1
Arguments to the job. Not valid if the script is entered from standard
input.
.sp 1
.I Qalter
allows changing this option even while the job executes. The modified
parameter will only be in effect after a restart or migration of the job,
however.
.sp 1
The number of command arguments is provided to configured JSV instances
as parameter with the name \fBCMDARGS\fP. Also the argument values
can by accessed. Argument names have the format \fBCMDARG<number>\fP where
\fB<number>\fP is a integer between 0 and \fBCMDARGS\fP - 1.
(see \fB\-jsv\fP option above or find more information concerning JSV in
.M jsv 1 )
.
.\"
.IP "\fBxterm_args\fP"
Available for \fIqsh\fP only.
.sp 1
Arguments to the
.M xterm 1
executable, as defined in the configuration.
For details, refer to
.M xxqs_name_sxx_conf 5 ).
.sp 1
Information concerning \fBxterm_args\fP will be available in JSV context as
parameters with the name \fBCMDARGS\fP and \fBCMDARG<number>\fP. Find more 
information above in section \fBcommand_args\fP. 
(see \fB\-jsv\fP option above or find more information concerning JSV in
.M jsv 1 )
.
.\"
.\"
.SH "ENVIRONMENTAL VARIABLES"
.\" 
.IP "\fBxxQS_NAME_Sxx_ROOT\fP" 1.5i
Specifies the location of the xxQS_NAMExx standard configuration
files.
.\"
.IP "\fBxxQS_NAME_Sxx_CELL\fP" 1.5i
If set, specifies the default xxQS_NAMExx cell. To address a xxQS_NAMExx
cell \fIqsub\fP, \fIqsh\fP, \fIqlogin\fP or \fIqalter\fP use (in the order of precedence):
.sp 1
.RS
.RS
The name of the cell specified in the environment 
variable xxQS_NAME_Sxx_CELL, if it is set.
.sp 1
The name of the default cell, i.e. \fBdefault\fP.
.sp 1
.RE
.RE
.\"
.IP "\fBxxQS_NAME_Sxx_DEBUG_LEVEL\fP" 1.5i
If set, specifies that debug information
should be written to stderr. In addition the level of
detail in which debug information is generated is defined.
.\"
.IP "\fBxxQS_NAME_Sxx_QMASTER_PORT\fP" 1.5i
If set, specifies the tcp port on which
.M xxqs_name_sxx_qmaster 8
is expected to listen for communication requests.
Most installations will use a services map entry for the
service "sge_qmaster" instead to define that port.
.\"
.IP "DISPLAY" 1.5i
For
.I qsh
jobs the DISPLAY has to be specified at job submission.
If the DISPLAY is not set by using the \fB\-display\fP or the \fB\-v\fP
switch, the contents of the DISPLAY environment variable are used as default.
.PP
In addition to those environment variables specified to be
exported to the job via the \fB\-v\fP or the \fB\-V\fP option
(see above)
\fIqsub\fP, \fIqsh\fP, and \fIqlogin\fP
add the following variables with the indicated values to the variable
list:
.sp 1
.IP "\fBSGE_O_HOME\fP" 1.5i
the home directory of the submitting client.
.IP "\fBSGE_O_HOST\fP" 1.5i
the name of the host on which
the submitting client
is running.
.IP "\fBSGE_O_LOGNAME\fP" 1.5i
the LOGNAME of the submitting client.
.IP "\fBSGE_O_MAIL\fP" 1.5i
the MAIL of the submitting client. This is 
the mail directory of the submitting client.
.IP "\fBSGE_O_PATH\fP" 1.5i
the executable search path of the submitting client.
.IP "\fBSGE_O_SHELL\fP" 1.5i
the SHELL of the submitting client.
.IP "\fBSGE_O_TZ\fP" 1.5i
the time zone of the submitting client.
.IP "\fBSGE_O_WORKDIR\fP" 1.5i
the absolute path of the current working directory of the
submitting client.
.PP
Furthermore, xxQS_NAMExx sets additional variables into the
job's environment, as listed below.
.IP "ARC"
.IP "SGE_ARCH" 1.5i
The xxQS_NAMExx architecture name of the node on which the job is
running. The name is compiled-in into the
.M xxqs_name_sxx_execd 8
binary.
.IP "SGE_BINDING" 1.5i
This variable contains the selected
operating system internal processor numbers.  They might be  more  than
selected  cores  in  presence  of SMT or CMT because each core could be
represented by multiple processor identifiers.  The  processor  numbers
are space separated.
.IP SGE_CKPT_ENV 1.5i
Specifies the checkpointing environment (as selected with the \fB\-ckpt\fP
option) under which a checkpointing job executes. Only set for checkpointing
jobs.
.IP "SGE_CKPT_DIR" 1.5i
Only set for checkpointing jobs. Contains path \fIckpt_dir\fP
(see
.M checkpoint 5
) of the checkpoint interface.
.IP SGE_CWD_PATH 1.5i
Specifies the current working directory where the job was started.
.IP SGE_STDERR_PATH 1.5i
the pathname of the file to which the standard error stream of the job is
diverted. Commonly used for enhancing the output with error messages
from prolog, epilog, parallel environment start/stop or checkpointing
scripts.
.IP SGE_STDOUT_PATH 1.5i
the pathname of the file to which the standard output stream of the job is
diverted. Commonly used for enhancing the output with messages from
prolog, epilog, parallel environment start/stop or checkpointing scripts.
.IP SGE_STDIN_PATH 1.5i
the pathname of the file from which the standard input stream of the job
is taken. This variable might be used in combination with xxQS_NAME_Sxx_O_HOST
in prolog/epilog scripts to transfer the input file from the submit
to the execution host.
.IP SGE_JOB_SPOOL_DIR 1.5i
The directory used by
.M xxqs_name_sxx_shepherd 8
to store job related data during job
execution. This directory is owned by root or by a xxQS_NAMExx administrative
account and commonly is not open for read or write access to regular users.
.IP SGE_TASK_ID 1.5i
The index number of the current array job task (see \fB\-t\fP option
above). This is an unique number in each array job and can be used to
reference different input data records, for example. This environment
variable is set to "undefined" for non-array jobs. It is possible to
change the predefined value of this variable with \fB\-v\fP or \fB\-V\fP
(see options above).
.IP SGE_TASK_FIRST 1.5i
The index number of the first array job task (see \fB\-t\fP option
above). It is possible to change the predefined value of this variable with
\fB\-v\fP or \fB\-V\fP (see options above).
.IP SGE_TASK_LAST 1.5i
The index number of the last array job task (see \fB\-t\fP option
above). It is possible to change the predefined value of this variable with
\fB\-v\fP or \fB\-V\fP (see options above).
.IP SGE_TASK_STEPSIZE 1.5i
The step size of the array job specification (see \fB\-t\fP option
above). It is possible to change the predefined value of this variable with
\fB\-v\fP or \fB\-V\fP (see options above).
.IP "ENVIRONMENT" 1.5i
The ENVIRONMENT variable is set to BATCH to identify that the job is being
executed under xxQS_NAMExx control.
.IP "HOME" 1.5i
The user's home directory path from the
.M passwd 5
file.
.IP "HOSTNAME" 1.5i
The hostname of the node on which the job is running.
.IP "JOB_ID" 1.5i
A unique identifier assigned by the
.M xxqs_name_sxx_qmaster 8
when the job was
submitted. The job ID is a decimal integer in the range 1 to 99999.
.IP "JOB_NAME" 1.5i
The job name. 
For batch jobs or jobs submitted by \fIqrsh\fP with a command, the job name is built as basename of the \fIqsub\fP script filename resp. the \fIqrsh\fP command.
For interactive jobs it is set to `INTERACTIVE' for \fIqsh\fP jobs, `QLOGIN' for \fIqlogin\fP jobs and `QRLOGIN' for \fIqrsh\fP jobs without a command.

This default may be overwritten by the
.I -N.
option.
.IP "JOB_SCRIPT" 1.5i
The path to the job script which is executed. The value can not be 
overwritten by the \fB\-v\fP or \fB\-V\fP option. 
.IP "LOGNAME" 1.5i
The user's login name from the
.M passwd 5
file.
.IP "NHOSTS" 1.5i
The number of hosts in use by a parallel job.
.IP "NQUEUES" 1.5i
The number of queues allocated for the job (always 1 for serial jobs).
.IP "NSLOTS" 1.5i
The number of queue slots in use by a parallel job.
.IP "PATH" 1.5i
A default shell search path of:
.br
.ta 5i
/usr/local/bin:/usr/ucb:/bin:/usr/bin
.IP "SGE_BINARY_PATH" 1.5i
The path where the xxQS_NAMExx binaries are installed. The value is the
concatenation of the cluster configuration value
.B binary_path 
and the architecture name
.B $SGE_ARCH
environment variable.
.IP "PE" 1.5i
The parallel environment under which the job executes (for parallel
jobs only).
.IP "PE_HOSTFILE" 1.5i
The path of a file containing the definition of the virtual parallel
machine assigned to a parallel job by xxQS_NAMExx. See the description of
the
.B $pe_hostfile
parameter in
.M xxqs_name_sxx_pe 5
for details on the format of this file. The environment variable
is only available for parallel jobs.
.IP "QUEUE" 1.5i
The name of the cluster queue in which the job is running.
.IP "REQUEST" 1.5i
Available for batch jobs only.
.sp 1
The request name of a job as specified with the
\fB\-N\fP switch (see above) or taken as the name of the job
script file.
.IP "RESTARTED" 1.5i
This variable is set to 1 if a job was restarted either after a system
crash or after a migration in case of a checkpointing job. The variable has
the value 0 otherwise.
.IP "SHELL" 1.5i
The user's login shell from the
.M passwd 5
file. \fBNote:\fP This is not necessarily the shell in use for the job.
.IP "TMPDIR" 1.5i
The absolute path to the job's temporary working directory.
.IP "TMP" 1.5i
The same as TMPDIR; provided for compatibility with NQS.
.IP "TZ" 1.5i
The time zone variable imported from
.M xxqs_name_sxx_execd 8
if set.
.IP "USER" 1.5i
The user's login name from the
.M passwd 5
file.
.IP "SGE_JSV_TIMEOUT" 1.5i
If the response time of the client JSV is greater than this timeout value, then the
JSV will attempt to be re-started. The default value is 10 seconds, and this value 
must be greater than 0. If the timeout has been reached, the JSV will only try to 
re-start once, if the timeout is reached again an error will occur.
.\"
.\"
.SH RESTRICTIONS
.PP
There is no controlling terminal for batch jobs under xxQS_NAMExx, and
any tests or actions on a controlling terminal 
will fail. If these operations are in
your .login or .cshrc file, they may cause your job to abort.
.PP
Insert the following test before any commands
that are not pertinent to batch jobs in your .login:
.PP
.nf
.RS
if ( $?JOB_NAME) then
.RS
echo "xxQS_NAMExx spooled job"
exit 0
.RE
endif
.RE
.fi
.PP
Don't forget to set your shell's search path in your
shell start-up before this code.
.\"
.\"
.SH EXIT STATUS
The following exit values are returned:
.IP "0" 0.5i
Operation was executed successfully.
.IP "25" 0.5i
It was not possible to register a new job according to the configured
.I max_u_jobs
or
.I max_jobs
limit. Additional information may be found in
.M sge_conf 5
.
.IP ">0" 0.5i
Error occurred.
.\"
.\"
.SH EXAMPLES
The following is the simplest form of a xxQS_NAMExx script file.
.nf

=====================================================


#!/bin/csh
   a.out


=====================================================
.fi
.sp 1
The next example is a more complex xxQS_NAMExx script.
.nf

=====================================================

#!/bin/csh                           
                        
# Which account to be charged cpu time 
#$ -A santa_claus

# date-time to run, format [[CC]yy]MMDDhhmm[.SS]
#$ -a 12241200                   

# to run I want 6 or more parallel processes
# under the PE pvm. the processes require
# 128M of memory
#$ -pe pvm 6- -l mem=128

# If I run on dec_x put stderr in /tmp/foo, if I
# run on sun_y, put stderr in /usr/me/foo
#$ -e dec_x:/tmp/foo,sun_y:/usr/me/foo

# Send mail to these users
#$ -M santa@nothpole,claus@northpole

# Mail at beginning/end/on suspension
#$ -m bes

# Export these environmental variables
#$ -v PVM_ROOT,FOOBAR=BAR

# The job is located in the current 
# working directory.
#$ -cwd

a.out

==========================================================

.fi
.\"
.\"
.SH FILES
.nf
.ta \w'$REQUEST.hostsJID[.TASKID]  'u
\fI$REQUEST.oJID[.TASKID]\fR	STDOUT of job #JID
\fI$REQUEST.eJID[.TASKID]\fR	STDERR of job
\fI$REQUEST.poJID[.TASKID]\fR	STDOUT of par. env. of job
\fI$REQUEST.peJID[.TASKID]\fR	STDERR of par. env. of job
.PP
.ta \w'<xxqs_name_sxx_root>/.xxqs_name_sxx_aliases   'u
\fI$cwd/.xxqs_name_sxx_aliases\fR	cwd path aliases
\fI$cwd/.xxqs_name_sxx_request\fR	cwd default request
\fI$HOME/.xxqs_name_sxx_aliases\fR	user path aliases
\fI$HOME/.xxqs_name_sxx_request\fR	user default request
\fI<xxqs_name_sxx_root>/<cell>/common/xxqs_name_sxx_aliases\fP
	cluster path aliases
\fI<xxqs_name_sxx_root>/<cell>/common/xxqs_name_sxx_request\fP
	cluster default request
\fI<xxqs_name_sxx_root>/<cell>/common/act_qmaster\fP
	xxQS_NAMExx master host file
.fi
.\"
.\"
.SH "SEE ALSO"
.M xxqs_name_sxx_intro 1 ,
.M qconf 1 ,
.M qdel 1 ,
.M qhold 1 ,
.M qmod 1 ,
.M qrls 1 ,
.M qstat 1 ,
.M accounting 5 ,
.M xxqs_name_sxx_aliases 5 ,
.M xxqs_name_sxx_conf 5 ,
.M xxqs_name_sxx_request 5 ,
.M xxqs_name_sxx_pe 5 ,
.M complex 5 .
.\"
.\"
.SH "COPYRIGHT"
If configured correspondingly,
.I qrsh
and
.I qlogin
contain portions of the
\fIrsh\fP, \fIrshd\fP, \fItelnet\fP and \fItelnetd\fP
code copyrighted by The Regents of the University of California.
Therefore, the following note applies with respect to \fIqrsh\fP and
\fIqlogin\fP: This
product includes software developed by the University of California,
Berkeley and its contributors.
.sp 1
See
.M xxqs_name_sxx_intro 1
as well as the information provided in <xxqs_name_sxx_root>/3rd_party/qrsh
and <xxqs_name_sxx_root>/3rd_party/qlogin
for a statement of further rights and permissions.
